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Commands for Agent 


Return 

Command 

Description 

[bool success] 

move [string direction] 

Attempts to move Agent in specified direction. 
/move?direction=forward 

[bool success] 

turn [string direction] 

Attempts to rotate Agent 90 degrees. 
/turn?direction=left 

[bool success] 

place [int slotNuml 

[string direction] 

Places a block in the selected inventory slot in 
direction specified. 

/place?slotNum=l&direction=left 

[bool success] 

till [string direction] 

Tills the soil with diamond hoe in direction specified. 
/till?direction=left 

[bool success] 

attack [string direction] 

Attacks in direction specified with diamond sword 
strength. 

/attack?direction=left 

[bool success] 

destroy [string direction] 

Destroys any types of block by single hit in direction 
specified. 

/destroy?direction=left 

[bool success] 

collect [string iteml 

Attempts to collect items. 

/collect?item=all 

[bool success] 

drop [int slotNuml 

[int quantitvl [string 

direction] 

Drops specified Inventory Slot Numbered Items in the 
specified quantity in the specified direction. 
/drop?slotNum=l&quantity=10&direction=right 

[bool success] 

dropall [string direction] 

Drops all Inventory Items in the specified direction. 
/dropall?direction=right 

[bool result] 

detect [string direction] 

Detects if there is a destructible Block in direction 
specified. 

/detect?direction=right 

[string blockName] 

inspect [string direction] 

Returns the name of the block in the specified 
direction. 

/inspect?direction=right 

[int data] 

inspectdata [string direction] 

Returns the data value of the block in the specified 
direction. 

/inspectdata?direction=right 

[bool result] 

detectredstone [string 

direction] 

Detects Redstone signal in specified direction. 
/detectredstone?direction=forward 

[string itemName] 

getitemdetail [int slotNuml 

Returns the item name in the specified slot. 
/getitemdetail?slotNum=l 

[int spaceCount] 

getitemspace [int slotNuml 

Returns the number of spaces remaining in the 
specified slot. 

/getitemspace?slotNum=l 

[int stackCount] 

getitemcount [int slotNuml 

Returns the number of items in the specified slot. 
/getitemcount?slotNum=l 

[bool success] 

transfer [int srcsIotNuml 

[int quantitvl fint 

dstslotNuml 

Transfers specified quantity of items from the 
selected slot to another specified slot of Agent's 
Inventory. 

/transfer?srcslotNum=l&quantity=64&dstslotNum=2 













































None 

tptoplaver 

Teleports Agent to player. 



/tptoplayer 


Commands for world {* indicates optional parameters) 


Return 

Command 

Description 

[int count] 

clone [blockpos beginl 

[blockpos end] [blockpos 

destination] *[string 

maskModel *[string 
cloneModel *[string tileNamel 

Copies blocks from one place to another. 

*[int tileDatal 

None 

executeasother [target originl 

[blockpos positionl [string 

commandl 

Executes another command as the specified 
target. Will fail if they don't have permission for 
the command. 

None 

executedetect 
[target originl [blockpos 

positionl [string detect] 

[blockpos detectPosl [string 

detectBlockl [int detectDatal 

[string commandl 

Executes another command if the block at the 
specified position matches the specified block 
type and data. 

[int fillCount] 

[string 

blockName] 

fill [blockpos froml [blockpos 

tol 

[string tileNamel 

*[int tileDatal 

*[string oldBlockHandlingl 

*[string replaceTileNamel 

*[int replaceDataValuel 

Fills the region with the specific block and data. 
What happens to existing blocks at the given 
locations is determined by oldBlockHandling. 

[string 

itemName] [int 

itemAmount] 

[string 

playerName] 

give [target plaverl [string 

itemNamel * Tint amountl 

Gives an item to a player. 

*fint datal 

None 

kill * [target targetl 

Kills entities (players, mobs, items, etc.). Default 
kills local player. 

None 

setblock 

[blockpos positionl 

[string tileNamel 

*[int tileDatal 

*[string oldBlockHandlingl 

Changes a block to another block. 

[bool 

wasSpawned] 

summon 

[string entitvTvpel 
[blockpos spawnPosl 

Tries to summon an entity at specified position. 

[bool matches] 

testforblock 

[blockpos positionl [string 

tileNamel 

Tests whether the specified block is at the 
specified location. 























































*fint dataValuel 


[int 

compareCount] 
[bool matches] 

testforblocks [blockpos beginl 

[blockpos endl [blockpos 

destination] *fstring model 

Tests whether the blocks in two regions match. 

None 

timesetbvname 

[string timel 

Sets in game time. 

None 

timesetbvnumber 

[int timel 

Sets in game time to 'day' or 'night'. 

None 

tptargettotarget [target victiml 

[target destination] 

*[int v-rotl 

*fint x-rotl 

Teleports target victim to target destination. 

None 

tptargettopos [target victiml 

[blockpos destination] 

*[int v-rotl 

*[int x-rotl 

Teleports target victim to destination position. 

None 

weather 
[string type] 

[int durationl 

Sets the weather for the specified duration. 


For more detail on world commands and their usage, go to: 
http://minecraft.gamepedia.com/Commands 































Using this API 

The Code Builder experience involves three apps: Minecraft: Education Edition (MC), Code 
Connection (CC), and an editor, presumably in a browser. The editor sends command requests in 
the form of REST queries to localhost on port 8080. CC picks these up, converts them into MC's 
JSON format, and sends them over WebSockets to MC. MC executes the command, sends 
output back to CC, which parses it and responds to the REST query. 

This means that to use CC it must be open and connected to MC. Once CC is on the editor 
selection screen it is ready to receive REST queries. There are two ways to accomplish this. 

• Run command /code in MC. This will launch CC and automatically connect. 

• Launch CC, then run command /connect localhost:19131 in MC. 


The Scratch implementation is available as an example here: 
https://github.com/Moiang/moiang.github.io 

REST Queries and Responses 

The app's rest server is listening on port 8080 and is used with queries of type "GET" specifying 
the command name followed by the arguments. Here is an example of a full (unencoded) URL: 


http://localhost:8080/drop?slotnum=l&quantity=l&direction=forward 

The app will always respond with JSON of some form. This will either be the expected return 
value, or an error code and message. Below is an example of possible return values of the 
"summon" command. 

{ 

wasSpawned: true 

} 

{ 

errorCode: 2 , 

errorMessage : "No WebSocket connection" 

} 

Format of "blockpos" 

All blockpos parameters will be passed as strings as if they were typed in Minecraft. Below is an 
example (unencoded) of an absolute position followed by a relative one. Relative positions are 
relative to the player, not the Agent. For more information visit: 
http://minecraft.gamepedia.com/Commands/ 


/exampleCommand?absolute=l 2 3 
/exampleCommand?relative=~l ~2 ~3 






Format of “target" 

Similar to blockpos, targets are also specified as they would be in a Minecraft command. Below 
are two (unencoded) examples of targets. For a more in-depth description of target syntax, visit: 
http://minecraft.gamepedia.com/Commands/ 

/exampleCommand?targetparam=Steve 

/exampleCommand?targetparam=@e[type=pig,x=l] 

URL Encoding 

Depending on the environment the REST queries are being made in it may be necessary to 
encode unsafe characters in the URLs for the commands. The app properly deals with encoded 
characters. Characters of concern are spaces, and characters from targets like '['']' and '='. 
Below is an example of this encoding. 

http://localhost:8080/example?target=@e[type=pig,x=l] 

Encoded to: 

http://localhost:8080/example?target=%40e%5Btype%3Dpig%2Cx%3Dl%5D 

Queueing Commands 

The extension that is performing the REST queries is responsible for queueing commands in such 
a way that there is only ever one pending command in this app. If multiple commands are 
initiated concurrently, all but the last will fail with error code 6 and only the last one will be 
executed. 

Command Permissions 

All Agent commands can be executed by any player. However, world commands require a higher 
permission level (mostly op) and will fail with error code 5 if the local player does not have the 
required permission level. 



Error Codes 


Value 

Description 

0 

Missing parameters in REST query. 

1 

App failed to parse parameter type, meaning it is either in 
an invalid format or not supported. 

2 

App is not connected to Minecraft and cannot run 
commands. 

3 

App encountered a WebSocket error and was unable to 
send the command. 

4 

The command was executed, but the app was unable to 
parse Minecraft's response. 

5 

The command failed on the Minecraft side, either because 
of invalid parameters or because the command hit a fail 
case. A common example would be specifying a target that 
doesn't get any results. The message from Minecraft will 
be appended onto the "errorMessage" field. 

6 

The pending command was cancelled because the app 
received a new REST query before the pending command 
was complete. 

7 

Invalid REST endpoint. 












move [string direction] 


/move?direction=forward 

Attempts to move Agent in specified direction. 

Parameters 

[string direction] 

forward, back, left, right, up, down 

Return 

[bool success] 

Returns if Agent moved in the direction specified. Would be false if he was blocked by 
a solid obstacle. 


turn [string direction] 


/turn?direction=left 

Attempts to rotate Agent 90 degrees. 

Parameters 

[string direction] 

Left, Right 

Return 

[bool success] 

Always returns true as the Agent cannot fail to turn. 


Dlace [int slotNum] [string direction] 


/place?slotNum=l&direction=left 

Right-clicks on the block in the specified direction. This basically places a block (ex: Place Stone Block) or a place- 
able item (ex: Place Oak Fence) from the selected Inventory Slot in the specified direction. However, this doesn't 
interact with things like doors, levers, and containers. Additionally, when player specifies a slot which contains 
the following non-place-able items, this behaves as follows: 

Get water/lava 


Bucket 


Till 


hoe 


Make a path 


shovel 


Spawn 


Spawn eggs 


Dye 


dyePowder 


Fire 


flint and steel 


fire charge (1 believe this is a fireball) 

Just drop 


Boat 

Minecart 


Bottle (try to make a bottle whatever you use it on, and be dropped) 

Parameters 

[int slotNum] 

Inventory Slot Number (1-27) 


[string direction] 

forward, back, left, right, up, down 

Return 

[bool success] 

Returns if a block in the specified inventory slot was placed. 























attack [string direction] 


/attack?direction=left 

Attacks in direction specified (diamond sword strength) 

Parameters 

[string direction] 

forward, back, left, right, up, down 

Return 

[bool success] 

Returns if the Agent damaged an entity. 


destroy [string direction] 


/destroy?direction=left 

Destroys breakable Block or Item in direction specified. Any breakable blocks can be broken in one hit. 

Parameters 

[string direction] 

Forward, Back, Left, Right, Up, Down 

Return 

[bool success] 

Returns if the Agent destroyed a block. This would be false if the block was 
unbreakable or wasn't solid, such as air or water. 


till [string direction] 


/till?direction=left 

Tills the soil by hoe in direction specified. 

Parameters 

[string direction] 

Forward, Back, Left, Right, Up, Down 

Return 

[bool success] 

Returns if the Agent could till, meaning it's a dirt-like material that can be turned into 
farmland. 


collect [string item] 


/collect?item=all 

Attempts to collect all items within a one block from Agent in three dimensions. 

Parameters 

[string item] 

all. Item name (stone, lapis_ore, etc.) Full list here: 
http://minecraft.gamepedia.com/Data values/Block IDs 

Filters by given type 

Return 

[bool success] 

Returns if any items were collected. 























drop [int slotNum] [int quantity] [string direction] 


/drop?slotNum=l&quantity=10&direction=right 

Drops the given number of items from the specified inventory slot onto the ground one block in the specified 
direction. 

Parameters 

[int slotNum] 

Inventory Slot Number (1-27) 


[int quantity] 

Quantity (1-64) 


[string direction] 

forward, back, left, right 

Return 

[bool success] 

Returns if any items were dropped. 


dropall [string direction] 


/dropall?direction=right 

Drops all items from all slots onto the ground one block in the specified direction. 

Parameters 

[string direction] 

forward, back, left, right 

Return 

[bool success] 

Returns if any items were dropped. 


detect [string direction] 


/detect?direction=right 

Detects if there is a collideable block in specified direction. Does not detect mobs. 

Parameters 

[string direction] 

forward, back, left, right, up, down 

Return 

[bool result] 

Returns if there was a collideable block in the specified direction. 


inspect [string direction] 


/inspect?direction=right 

Returns the name of the block in the specified direction. 

Parameters 

[string direction] 

forward, back, left, right, up, down 

Return 

[string itemName] 

Of the form "coal_ore". Full list here: 
htto://minecraft.eameoedia.com/Data values/Block IDs 
























inspectdata [string direction] 


/inspectdata ?direction=right 

Returns the data value of the block in the specified direction. 

Parameters 

[string direction] 

forward, back, left, right, up, down 

Return 

[int data] 

Data value of the block in the specified direction, 0 for air. 


detectredstone [string direction] 


/detectredstone?direction=forward 

Detects Redstone signal in specified direction. 

Parameters 

[string direction] 

forward, back, left, right, up, down 

Return 

[bool result] 

Returns if the object in the specified direction is receiving Redstone power at that 

moment. 


getitemdetail [intslotNum] 


/getitemdetail ?slotNum=l 

Returns the name of the item in the specified slot. 

Parameters 

[int slotNum] 

Inventory Slot Number 

Return 

[string itemName] 

Returns item name of the form "coal_ore". Full list here: 
htto://minecraft.eameoedia.com/Data values/Block IDs 


getitemspace [intslotNum] 


/getitemspacePslotNum 

=1 

Returns the number of spaces remaining in the specified slot, as in the number of items you could add before it 

would be full. 


Parameters 

[int slotNum] 


Inventory Slot Number 

Return 

[int stackCount] 


getitemcount [intslotNum] 


/getitemcount?slotNum=l 

Returns the number of items in the specified slot, as in how many you could use before it would be empty. 

Parameters 

[int slotNum] 

Inventory Slot Number 

Return 

[int stackCount] 

Returns the number of items in the specified slot. 








































transfer [int srcsIotNum] [int quantity] [int dstslotNum] 


/transfer?srcslotNum=l&quantity=64&dstslotNum=2 

Transfers specified quantity of items from the selected slot to another specified slot of Agent's Inventory. 

Parameters 

[int srcsIotNum] 

Source Inventory Slot Number 

[int quantity] 

Quantity (1-64) 

[int dstslotNum] 

Destination Inventory Slot Number 

Return 

[bool success] 

If the destination slot already has items of a different type, it will return false (does not 
try to fill the next slot). If there are fewer than the specified quantity of items in the 
selected slot or only room for fewer items in the destination slot, it will transfer as 
many as possible and return true. If none can be transferred, it returns false. 


tptoplayer 


/tptoplayer 

Teleports the Agent to the player's feet. 

Parameters 

None 

Return 

None 












Item list (1.1) 


Blocks: 

acacia_stairs,al low,bed rock,birch_stairs, border_block,brick_block,brick_stairs,clay,coal_ore,cob 
blestone,dark_oak_stairs,deny,diamond_ore,dirt,emerald_ore,end_bricks,end_stone,gold_ore,g 
rass,gravel,hardened_clay,ice, iron_ore,jungle_stairs,lapis_ore,log, log2,mossy_cobblestone,myc 
elium,nether_brick,nether_brick_stairs,netherbrick,netherrack,oak_stairs,obsidian, packed_ice,p 
lanks, podzol, prismarine,purpur_block,purpur_stairs,qua rtz_block,qua rtz_ore,quartz_stairs,red_ 
sandstone,red_sandstone_stairs,redstone_ore,sand,sandstone,sandstone_stairs,snow,soul_san 
d,spruce_stairs,stained_hardened_clay,stone,stone_brick_stairs,stone_slab,stone_slab2,stone_ 
stairs,stonebrick,wooden_slab 

Decorations: 

acacia_door,acacia_fence_gate,anvil,beacon,bed,birch_door,birch_fence_gate,black_glazed_ter 
racotta,blue_glazed_terracotta, board, bookshelf, brewing_stand,brown_glazed_terracotta, brow 
n_mushroom,brown_mushroom_block,cactus,cake,carpet,cauldron,chest,coal_block,cobblesto 
ne_wall,concrete,concretepowder,crafting_table,cyan_glazed_terracotta,dark_oak_door,dark_o 
ak_fence_gate,dead bush,diamond_block,double_plant,dragon_egg,emerald_block,enchanting_ 
table, end_crystal,end_portal_frame,end_rod,ender_chest, fence, fence_gate,flower_pot, frame, f 
urnace,glass,glass_pane,glowstone,gold_block,gray_glazed_terracotta,green_glazed_terracotta, 
hay_block,iron_bars,iron_block,iron_door,iron_trapdoor,jungle_door,jungle_fence_gate, ladder, 
lapis_block,leaves, leaves2,light_blue_glazed_terracotta,lime_glazed_terracotta,lit_pumpkin,ma 
genta_glazed_terracotta,melon_block,mob_spawner,monster_egg,nether_brick_fence,notebloc 
k,orange_glazed_terracotta, painting, pink_glazed_terracotta, pumpkin, purple_glazed_terracotta, 
red_flower,red_glazed_terracotta,red_mushroom,red_mushroom_block,redstone_block,sapling 
, sealantern, shulker_box, sign, silver_glazed_terracotta, skull, slime, snowjayer, sponge, spruce_do 
or,spruce_fence_gate,stonecutter,tallgrass,trapdoor,trapped_chest,vine,waterlily, web,white_gl 
azed_terracotta,wooden_door, wool,yellow_f lower,yellow_glazed_terracotta 

Miscellaneous: 

apple,appleenchanted, arrow, baked_potato, beef, beetroot, beetroot_seeds,beetroot_soup, blaze 
_powder,blaze_rod, bone, book, bowl,bread,brick,carrot,carrotonastick,chicken,chorus_f lower,ch 
orus_fruit,chorus_fruit_popped,chorus_plant,clay_ball,clownfish,coal,cooked_beef,cooked_chic 
ken, cooked_fish,cooked_porkchop,cooked_rabbit,cooked_salmon, cookie, diamond, dragon_brea 
th,dye,egg,emerald,emptymap,enchanted_book,experience_bottle,feather,fermented_spider_e 
ye,fish,flint,ghast_tear,glass_bottle,glowstone_dust,gold_ingot,gold_nugget,golden_apple,golde 
n_carrot,gunpowder,ironjngot, iron_nugget, leather,lingeri ng_potion,magma_cream,melon,mel 
on_seeds,mushroom_stew,muttoncooked, mutton raw, nether_wart,netherstar,paper,poisonous 
_potato,porkchop, potato, potion, prismarine_crystals,prismarine_shard,pufferfish,pumpkin_pie, 
pumpkin_seeds,quartz,rabbit,rabbit_foot,rabbit_hide,rabbit_stew,reeds,rotten_flesh,salmon,sh 
ulker_shell,slime_ball,speckled_melon,spider_eye,splash_potion,stick,string,sugar, wheat,wheat 
seeds 


Tools: 


activator_rai I, boat,bow, bucket,camera,chain_command_block,chainmail_boots,chainmail_ches 
tplate,chainmail_helmet,chainmail_leggings,chest_minecart,clock,comma nd_block,comma nd_b 
lock_minecart, comparator, compass, daylight_detector,detector_rail,diamond_axe,diamond_bo 
ots,diamond_chestplate,diamond_helmet,diamond_hoe,diamond_leggings,diamond_pickaxe,di 
amond_shovel,diamond_sword,dispenser,dropper,elytra,ender_eye,ender_pearl, fire ball, fishing 
_rod,flint_and_steel,golden_axe,golden_boots,golden_chestplate,golden_helmet,golden_hoe,g 
olden_leggings,golden_pickaxe,golden_rail,golden_shovel,golden_sword,heavy_weighted_press 
ure_plate,hopper,hopper_minecart,horsearmordiamond,horsearmorgold,horsearmoriron, horse 
armorleather,iron_axe,iron_boots,iron_chestplate,iron_helmet,iron_hoe,iron_leggings,iron_pic 
kaxe,iron_shovel,iron_sword,lead,leather_boots,leather_chestplate,leather_helmet,leather_leg 
gings, lever, light_weighted_pressure_plate, minecart, nametag, observer, piston, portfolio, rail, reds 
tone,redstone_lamp,redstone_torch,repeater,repeating_command_block,saddle,shears,snowba 
ll,spawn_egg,sticky_piston,stone_axe,stone_button,stone_hoe,stone_pickaxe,stone_pressure_ 
plate, stone_shovel,stone_sword,structure_block,tnt,tnt_minecart, torch, totem, tripwire_hook,w 
ooden_axe,wooden_button,wooden_hoe,wooden_pickaxe,wooden_pressure_plate,wooden_sh 
ovel,wooden_sword 


